Hybris Sales UX API

Query Service Qualification is used to retrieve a list of service eligible in a given request provided by requester (via searchCriteria).

URL

https://[localhost]:[port]/ecom-sales-ux/v1/{businessId}/queryServiceQualification

URL Params

Headers

Query Params

Data Model - Response

searchCriteria.service.place[] subResource - dataModel

serviceQualificationItem[].service.feature[].featureCharacteristic[] subResource - dataModel

serviceQualificationItem[].service.feature[] subResource - dataModel

serviceQualificationItem[].service.serviceCharacteristic[] subResource - dataModel

serviceQualificationItem[].service.place[].GeographicAddress[]

serviceQualificationItem[].service.place[]

serviceQualificationItem[].service.place[].geographicSubAddress[]

Key Consideration:

• Please refer the examples from the following URL - ecom-sales-ux - GET queryServiceQualification

This API is available for all five BUs (JM, PA, CR, PR,CL ). Below are the common key points:

1. API expects the below-mentioned query parametersoffset, limit, searchCriteria

2. Example for queryParam searchCriteria object,

   {
   
   "id": "9090",
   "streetNr": "225",
   "streetName": "Strathmore",
   "postcode": "5004",
   "locality": "Brighton",
   "city": "Brighton",
   "stateOrProvince": "SA",
   "country": "Australia",
   "latitude": "1.430937",
   "longitude": "43.597208"
   }

3. SouthBound Systems For Jamaica, Panama and Costa Rica, ArcGIS is providing serviceability information. For LCPR, Marvin DB is providing serviceability information. For Chile, Siebel is providing serviceability information.
4. In response, field “serviceQualificationItem/service/feature/featureCharacteristic/name” represents access technology type like (FTTX, HFC, CU).

For Jamaica

1. For Jamaica, only latitude and longitude are expected from the front end. Mule API will throw an error if these details are missing.

searchCriteria = {

"latitude": "10.03",
"longitude":"84.04"

}

URL encoded: searchCriteria= %7B%0A%09%22latitude%22%3A%20%2210.03%22%2C%0A%09%22longitude%22%3A%2284.04%22%0A%7D%0A

1. Service qualification response may have multiple service qualification items (serviceQualificationItem[]) based on polygons returned by ArcGIS (sorted by access technology priority (FTTX, HFC, CU) and address class priority).
2. In HFC, network mode can be FUDIG, ANDIG and ANALO.
3. In response, field “serviceQualificationItem/service/feature/featureCharacteristic/name =” priority” represents priority of polygon.FTTX = priority 1

HFC = priority 2

Copper/CU = priority 3

1. As we are not getting commercial status, plant capacity and return type(Full-duplex and half-duplex), we are assuming that

a. All addresses are commercially available.

b. Node has capacity available to serve location.

c. VOD (video on demand) may not be available for some locations, but we will not be able to tell customers as this info does not exist in GIS in Jamaica.

1. In response, if all serviceQualificationItem have the same priority polygons with the same address class, priority will be given to the polygon that appears at the first index in the array.
2. In response, if serviceQualificationItem[] is an empty array means no polygon coverage for requested longitude and latitude hence no serviceability.
3. In response, if “serviceQualificationItem/service/feature/featureCharacteristic[x]/name” =”node_status” and “serviceQualificationItem/service/feature/featureCharacteristic[x]/value”=”E” location is serviceable. If “value” is “P” or “U”, location i s not serviceable.
4. If response has only one serviceability object with priority 3 and serviceQualificationItem/service/feature/featureCharacteristic/name = CU then location is not serviceable.
5. If response has only one serviceability object with serviceQualificationItem/service/feature/featureCharacteristic/name =HFC and serviceQualificationItem/service/feature/featureCharacteristic[x]/name = "netModeHfc" and value = "ANALO" then location is not serviceable.

For Panama

1. For Panama, only latitude and longitude are expected from the front end. Mule API will throw an error if these details are missing.

   searchCriteria =

   {
   "latitude": "10.03",
   "longitude":"84.04"
   }

   URL encoded: searchCriteria= %7B%0A%09%22latitude%22%3A%20%2210.03%22%2C%0A%09%22longitude%22%3A%2284.04%22%0A%7D%0A

2. Service qualification response may have multiple service qualification items (serviceQualificationItem[]) based on polygons returned by ArcGIS (sorted by access technology priority (FTTX, HFC).
3. In HFC, network mode is FUDIG only for Panama.
4. As we are not getting commercial status, plant capacity and return type(Full-duplex and half-duplex), we are assuming that a. All addresses are commercially available. b. Node has capacity available to serve location. c. VOD (video on demand) may not be available for some locations, but we will not be able to tell customers as this info does not exist in GIS.
5. In response, if all serviceQualificationItem have the same priority polygons, priority will be given to the polygon that appears at the first index in the array.
6. In response, if serviceQualificationItem[] is an empty array means no polygon coverage for requested longitude and latitude hence no serviceability.
7. In response, when serviceQualificationItem[].service.serviceCharacteristic[].name = feat_type, the value will be service for serviceability and address for addressability.
8. For addressability, the OneID retrieved from ArcGIS is mapped to serviceQualificationItem[].service.place[].GeographicAddress[].id. If the OneID is not available, the API returns an empty string for OneID field.
9. For addressability enhancement, the date-format is updated to include offset (example: 2026-01-06T16:22:54.210-05:00).

For CostaRica

1. In Costa Rica, the ArcGIS system expects Latitude and Longitude value for serviceability. API will throw an error if Lat and Long are missing in the request.

searchCriteria = {

"latitude": "10.03",
"longitude":"84.04"

}

URL encoded: searchCriteria= %7B%0A%09%22latitude%22%3A%20%2210.03%22%2C%0A%09%22longitude%22%3A%2284.04%22%0A%7D%0A

1. Service qualification response may have multiple service qualification items (serviceQualificationItem[]) based on polygons returned by ArcGIS (sorted by access technology priority (FTTH, HFC) and address class priority).
2. In response, field “serviceQualificationItem/service/feature/featureCharacteristic/name” represents access technology type FTTH or HFC.
3. In response, field “serviceQualificationItem/service/feature/featureCharacteristic/name =” priority” represents priority of polygon. • Fiber – priority 1• HFC (address class =” Metro”) - priority 2• HFC (address class =” Rural”) - priority 3
4. In response, field “serviceQualificationItem/service/feature/featureCharacteristic/name =” addressClass” represents the below mentioned polygon address class. • Metro• Rural
5. In response, if all serviceQualificationItem have the same priority polygons with the same address class, priority will be given to the polygon that appears at the first index in the array.
6. In response, if all serviceQualificationItem objects have the same priority (overlapping HFC polygons), but the address class has a different value (Metro or Rural ), then priority will be based on the address class.
7. In response, if serviceQualificationItem[] is an empty array means no polygon coverage for requested longitude and latitude hence no serviceability.

For Chile

1. For Chile, the searchCriteria query param value will be JSON object with URL encoding#Example:

searchCriteria= { "latitude": "10.03", "longitude":"84.04"}

URL encoded: %7B%0A%09%22latitude%22%3A%20%2210.03%22%2C%0A%09%22longitude%22%3A%2284.04%22%0A%7D%0ANote:

In case of missing query param or longitude and latitude or Id, API will throw an error.

The MuleSoft API response will have a maximum number of 100 queryServiceQualification objects, sorted by GIS_ID (place.id) for requested latitude and longitude values. 100 records restriction is from the Siebel side and is configurable.

In BSS, there may be more than 100 records corresponding to the requested latitude and longitude value. For getting the rest of the available records, the front end needs to set the offset value as 101 and hit the API again with the same payload. If the total number of records is less than 100 means no more records are available in BSS.For example, if Siebel finds 120 records for requested latitude and longitude for the first get call (Initial offset value is 1), the API will return the first 100 queryServiceQualification objects.

- If the offset is 21, the API will return the last 100 records.
- If the offset 11, the API will return the records from 11th to 110.

1. Custom response header “x-result-count” returns the number of items returned in the response body. It can be used to set offset value for iterative API call.
2. If no offset is sent by the front end, then the default Offset value is 1.
3. In the API response, the field “serviceQualificationItem.service.place.id” returns GIS House ID for the house. House id is mandatory for customer registration..
4. In API response, field serviceQualificationItem/service/serviceType represents the services available for installation. If serviceType=” null” means no service available on a given address hence no serviceability. Other possible values are,

Please Note:

. Voice –No standalone Voice sell in Ecomm (almost zero sales so out of scope).

Internet – No standalone internet sell in Ecomm.

if the location has 3PLAY customer can have any combination for 2PLAY or 1PLAY.

1. In response, field “serviceQualificationItem.service.feature.name” returns Network type/technology type: FTTH or HFC and is required for serviceability decision.
2. In response, field serviceQualificationItem.service. feature. feature Characteristic. name =”returnType” represents the mode of transmission. This field needs to be considered if feature.name=HFC. This field doesn’t impact serviceability but impacts user experience.
3. If returnType value =”FULLDUPLEX”, the customer can enjoy VOD (video on demand). VOD is free of charge and included for free for all customers those lives in a place where the network is a fullduplex.
4. If returnType value =”HALFDUPLEX”, the customer can not enjoy VOD (video on demand).
5. In API response if field “serviceQualificationItem.service.serviceCharacteristic.name =” comercialStatus” and value = “N” It means no serviceability.
6. In the API response, if the field “serviceQualificationItem.service.serviceCharacteristic.name =”addressStatus” and value = “INACTIVE” means the address is invalid hence no serviceability..
7. In the API response, if field serviceQualificationItem.service.serviceCharacteristic.name ="isNodeCapacityFull" and Value =” Y” then it means Node is not able to serve any new address hence no serviceability.
8. In the API response, if field serviceQualificationItem.service.feature.name = “HFC” and serviceQualificationItem.service.serviceCharacteristic.name="networkMode" and Value = “ANALO” Or “ANPRE” OR “SINRE” then as per business there will be no TV offer available in hybris for customer hence no serviceability and customer must be redirected to “Click to Call”This rule is not applicable to FTTH.
9. Please find below table for Serviceability summery

For Puerto Rico

1. In Puerto Rico, the local Marvin DB (copy of CSG DB) system expects a unique House ID to provide Services available on that specific house. API will throw an error if House ID is missing in the request.

Example:

searchCriteria = {"id": "662423423"}

The value will be JSON object with URL encoding.

1. Service availability response may have multiple service available items based on Local Marvin DB and sorted by access technology like TV/VOICE/INTERNET/1GB_OFFER.
2. As Puerto Rico eCom's requirement is to check only 4 services on an address, API will return the status of the services.
3. Technology details, ‘FTTH or COAX’ has been added in response and eCom can consider it if there is any requirement, while these are not available in Marvin DB in all the records.
4. attribute "startMode" will define about the location is self install or not and possiable values of "startMode" are 1) selfInstallEnabled - Location eligable to self install2) selfInstallDisabled - Location not-eligable to self install3) unknown - location would be new or techinicain not visited.